home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / util / Stack.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  3.7 KB  |  126 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Stack.java    1.22 98/09/27
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * The <code>Stack</code> class represents a last-in-first-out 
  19.  * (LIFO) stack of objects. It extends class <tt>Vector</tt> with five 
  20.  * operations that allow a vector to be treated as a stack. The usual 
  21.  * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
  22.  * method to <tt>peek</tt> at the top item on the stack, a method to test 
  23.  * for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt> 
  24.  * the stack for an item and discover how far it is from the top.
  25.  * <p>
  26.  * When a stack is first created, it contains no items. 
  27.  *
  28.  * @author  Jonathan Payne
  29.  * @version 1.22, 09/27/98
  30.  * @since   JDK1.0
  31.  */
  32. public
  33. class Stack extends Vector {
  34.     /**
  35.      * Creates an empty Stack.
  36.      */
  37.     public Stack() {
  38.     }
  39.  
  40.     /**
  41.      * Pushes an item onto the top of this stack. This has exactly 
  42.      * the same effect as:
  43.      * <blockquote><pre>
  44.      * addElement(item)</pre></blockquote>
  45.      *
  46.      * @param   item   the item to be pushed onto this stack.
  47.      * @return  the <code>item</code> argument.
  48.      * @see     java.util.Vector#addElement
  49.      */
  50.     public Object push(Object item) {
  51.     addElement(item);
  52.  
  53.     return item;
  54.     }
  55.  
  56.     /**
  57.      * Removes the object at the top of this stack and returns that 
  58.      * object as the value of this function. 
  59.      *
  60.      * @return     The object at the top of this stack (the last item 
  61.      *             of the <tt>Vector</tt> object).
  62.      * @exception  EmptyStackException  if this stack is empty.
  63.      */
  64.     public synchronized Object pop() {
  65.     Object    obj;
  66.     int    len = size();
  67.  
  68.     obj = peek();
  69.     removeElementAt(len - 1);
  70.  
  71.     return obj;
  72.     }
  73.  
  74.     /**
  75.      * Looks at the object at the top of this stack without removing it 
  76.      * from the stack. 
  77.      *
  78.      * @return     the object at the top of this stack (the last item 
  79.      *             of the <tt>Vector</tt> object). 
  80.      * @exception  EmptyStackException  if this stack is empty.
  81.      */
  82.     public synchronized Object peek() {
  83.     int    len = size();
  84.  
  85.     if (len == 0)
  86.         throw new EmptyStackException();
  87.     return elementAt(len - 1);
  88.     }
  89.  
  90.     /**
  91.      * Tests if this stack is empty.
  92.      *
  93.      * @return  <code>true</code> if and only if this stack contains 
  94.      *          no items; <code>false</code> otherwise.
  95.      */
  96.     public boolean empty() {
  97.     return size() == 0;
  98.     }
  99.  
  100.     /**
  101.      * Returns the 1-based position where an object is on this stack. 
  102.      * If the object <tt>o</tt> occurs as an item in this stack, this 
  103.      * method returns the distance from the top of the stack of the 
  104.      * occurrence nearest the top of the stack; the topmost item on the 
  105.      * stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt> 
  106.      * method is used to compare <tt>o</tt> to the 
  107.      * items in this stack.
  108.      *
  109.      * @param   o   the desired object.
  110.      * @return  the 1-based position from the top of the stack where 
  111.      *          the object is located; the return value <code>-1</code>
  112.      *          indicates that the object is not on the stack.
  113.      */
  114.     public synchronized int search(Object o) {
  115.     int i = lastIndexOf(o);
  116.  
  117.     if (i >= 0) {
  118.         return size() - i;
  119.     }
  120.     return -1;
  121.     }
  122.  
  123.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  124.     private static final long serialVersionUID = 1224463164541339165L;
  125. }
  126.